home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / os2 / vsoup11.zip / readme < prev    next >
Text File  |  1996-09-02  |  12KB  |  359 lines
  1. $Id: readme 1.6 1996/09/02 13:31:33 hardy Exp $    
  2.  
  3. THIS PROGRAM IS HEAVILY BASED ON IDEAS/MODULES/DOCS FROM CHIN HUANGs
  4. (cthuang@io.org) SOUPER15.  THANKS TO HIM.  ALSO FOR YARN/2.
  5.  
  6. This means, that bug reports and everything else concerning VSoup
  7. should be directed to Hardy Griech (rgriech@ibm.net, no Chin Huang!
  8.  
  9. VSoup is free software.  See COPYING disclaimer of the FSF for
  10. details.  Note that you are not allowed to distribute VSoup without
  11. source code.
  12.  
  13.  
  14. Purpose
  15. =======
  16.  
  17. VSoup is a network mail and news client program for OS/2 Warp's
  18. Internet Access Kit.  It transfers mail and news fetched from a POP3
  19. server and NNTP server respectively to SOUP format.  It can also send
  20. messages in SOUP reply packets to NNTP/SMTP servers
  21.  
  22. Currently there are no man pages for VSoup.  The man pages from
  23. souper15 and the usage message should be enough (temporary).
  24.  
  25. The program requires the emx run-time DLLs.  You can get these from
  26.  
  27.      ftp://ftp-os2.nmsu.edu/os2/unix/emx09b/emxrt.zip
  28.  
  29.  
  30. Features
  31. ========
  32.  
  33. -  receiving news from NNTP, posting news to NNTP, receiving mail from
  34.    POP3, sending mail to SMTP
  35.  
  36. -  all the packets are exchanged in SOUP format files
  37.  
  38. -  multi-threaded news receiving
  39.  
  40. -  status mail generation (this is not in SOUP standard, but
  41.    recognized by YARN).  The generation can be forced via command line
  42.    option, standard is to generate mail in case of failure or on new
  43.    newsgroups (-a option)
  44.  
  45. -  detects time-out condition for news receiving
  46.  
  47. -  URLs on command line for easy specification of the several servers
  48.  
  49. -  example (!) script to do VSoup operation safely (without risc of
  50.    message loss etc.)
  51.  
  52.  
  53. CmdLine
  54. =======
  55.  
  56. Common command options
  57. ----------------------
  58.  
  59. -h dir      set the home directory for the VSoup operation.  You can
  60.             also specify your home directory through the environment
  61.             variable HOME
  62.  
  63. -i          ignore the settings of the 'Internet Connection for OS/2'
  64.             settings
  65.  
  66. -m          do not fetch mail
  67.  
  68. -M          generate the VSoup status mail in any case.  Standard is
  69.             to generate the message in case of error only.
  70.  
  71. -n          do not fetch news
  72.  
  73. -r          read only mode.  Except the *.msg ./areas, ./*.msg ./*.idx
  74.             no files are written (e.g. ~/newstime, ~/newsrc).  Also
  75.             the mails are not deleted from the POP3 server.  Main
  76.             purpose for this option is debugging.
  77.  
  78. -s          send replies.  -s might be combined with the -m,-n option,
  79.             but this feature is ignored!
  80.  
  81. News receiving options
  82. ----------------------
  83.  
  84. -a          add new newsgroups to newsrc file.  If there are any new
  85.             groups on the server, then the generation of the status
  86.             message will be forced.
  87.  
  88. -c[n]       catchup: mark every article as read except for the last n
  89.             (default is 10).
  90.  
  91. -k n        set maximum news packet size to n KBytes (default is no
  92.             limit).  N means the total amount of received messages,
  93.             not the size of a single message (see -l)
  94.  
  95. -K file     set the name of the kill file (see note below...)
  96.  
  97. -l n        set the maximum length of news you like to receive.  This
  98.             is intended for omitting binaries in text groups.
  99.  
  100. -N file     set the name of the newsrc file (see note below...)
  101.  
  102. -t n        receive the news with 'n' threads, i.e. connect to the NNTP
  103.             server 'n' times
  104.  
  105. -u          create news summary.  Output can be found in the ./*.IDX
  106.             files.  Be aware that the summarized articles are marked
  107.             as read (one way to get out of this, is to call VSoup with
  108.             -r)
  109.  
  110. -x          do not process news Xref headers
  111.  
  112. -K,-N,-h
  113. --------
  114.  
  115. I do not recommend to use these options, because behavior is not very
  116. transparent if you are using also '-h'.  If the '-h' is behind the
  117. '-K/-N' the result will be another as expected - vsoup (and souper)
  118. will revert to 'kill' and 'newsrc'; if '-K/-N' are behind the '-h' and
  119. do not contain absolute pathes, the will not be located in the by '-h'
  120. specified home directory.  This is confusing and will be fixed in a
  121. future release.  IT IS BETTER AND CLEANER TO USE -h AND SETUP THE
  122. SPECIAL KILL/NEWSRC FILES IN THAT DIRECTORY!
  123.  
  124. URLs
  125. ----
  126.  
  127. The addresses of the hosts are given in URL form.  These confirms not
  128. absolutely to the standard, so a short explanation follows:
  129.  
  130. -  'nntp://[UserId[:Password]@]nntp-host' defines the address of your
  131.    NNTP server.  UserId and Password can be given if required for
  132.    AUTHINFO.
  133.  
  134. -  'pop3://[UserId[:Password]@]pop3-host' defines the address of your
  135.    POP3 server.  UserId and Password are usually required.
  136.  
  137. -  'smtp://[userid[:password]@]smtp-gateway' defines your SMTP
  138.    gateway.  UserId and Password are not required, in fact they are
  139.    ignored by VSoup!
  140.  
  141. This feature makes VSoup dfferent to souper16, which wants to see a
  142. ~/newsauth file.
  143.  
  144. Ah ja: it is not intended to implement other protocols like http or
  145. so...
  146.  
  147.  
  148. Environment
  149. ===========
  150.  
  151. HOME         your home directory (can also be specified in the command
  152.              line)
  153.  
  154. NNTPSERVER   hostname of the nntp server (can also be specified in the
  155.              command line)
  156.  
  157.  
  158. Diagnostics
  159. ===========
  160.  
  161. VSoup returns with an exit code of '1', if any operation failed.
  162. Otherwise return code will be '0'.
  163.  
  164.  
  165. Evaluation Order Of URLs
  166. ========================
  167.  
  168. Evaluation order is as follows:
  169.  
  170. (1)  take all information from the 'Internet Connection for OS/2'
  171.      settings
  172.  
  173. (2)  check the NNTPSERVER environment settings (yes, there are no vars
  174.      for the SMTP/POP3 setup).  NNTPSERVER is a URL without leading
  175.      'nntp://'
  176.  
  177. (3)  command line options
  178.  
  179. If you specify only e.g. 'nntp://news-server' in the command line
  180. (without userid/password), the userid/password from the OS/2 settings
  181. are taken as a standard value.
  182.  
  183.  
  184. News Reception
  185. ==============
  186.  
  187. for news reception you have the following options (which cannot
  188. combined): either process ./commands (./commands exists), or catch-up
  189. the newsgroups (-c option) or create newsgroups summary (-u option) or
  190. receive the news in the standard way (no specific option).  New
  191. newsgroups are added only to the ~/newsrc file, if news received in
  192. the standard way.
  193.  
  194.  
  195. Helper
  196. ======
  197.  
  198. There is a REXX script packed into this archive.  The script is just
  199. intended as an example and must be adapted to your special needs.  If
  200. somebody wants to make the configuration easier, she/he is welcome.
  201.  
  202. yarnio.cmd:    control IO of VSoup to YARN.  News are read from two
  203.                NNTP servers, mail/news are transmitted, mail is
  204.                received - all simultaneously.  The cmd should be
  205.                started by the dialer directly after connection has
  206.                been established.  Sorry, but the directory structure
  207.                must be adapted manually!
  208.  
  209.  
  210. Files
  211. =====
  212.  
  213. ~/newsrc:       contains the newsgroups.  ':' behind the name
  214.                 indicates subscribed group, '!' indicates an
  215.                 unsubscribed one
  216.  
  217. ./commands:     contains lines with the syntax: 'sendme' <groupname>
  218.                 <article-nums>.  ./commands is executed instead of
  219.                 standard fetching of news.  After successful
  220.                 'commands'-processing, the file will be deleted.
  221.                 Note: already read articles (marked in ~/newsrc) will
  222.                 be skipped!
  223.  
  224. ~/kill:         is the kill file.  Note: news transmission speed
  225.                 decreases if a kill file is used, because then an
  226.                 article is fetched in two steps: HEAD <num>, then BODY
  227.                 <num>.  Otherwise an article will be fetched in only
  228.                 one step: ARTICLE <num>
  229.  
  230. ~/newstime:     contains the time of the last NNTP connection.  This
  231.                 is for fetching of new newsgroups.  If ~/newstime does
  232.                 not exist, ALL currently available newsgroups are
  233.                 fetched from the server.  Applicable only, if VSoup
  234.                 was called with the '-a' paramet